Introduction

For this course, we will use Docker, a platform that allows us to run software in containers, which are like lightweight virtual machines. A Docker image is a preconfigured environment that contains all the software, tools, and data you need for the course. Using Docker ensures that everyone has the same setup, avoids compatibility issues, and makes it easy to start working on the practical exercises without worrying about installing multiple programs individually.

This guide explains how to install Docker Desktop, obtain the Docker image with the command-line tools required by the course instructors, run a container on your laptop, and test the programs and data you will use in class.

Installing Docker

To work with images and containers, you need DockerDesktop` installed on your computer. Find instructions here:


Remember that you may need to use sudo for administrative commands if you are not logged in as root in your computer.

WINDOWS USERS: You will need to enable WSL (Windows Subsystem for Linux), which is a lightweight Linux virtual machine included by default in Windows. Note that on some older laptops or certain new hardware (some kernels), enabling WSL or running Docker on Windows can cause issues. If this happens, contact me, and we can try to fix it online or schedule a meeting before.

To verify Docker installation, open the terminal (or PowerShell on Windows) and type:

docker --version
docker run hello-world

Getting the Docker image for the course

The Docker image for this course is available on Docker Hub, a cloud-based repository where Docker images are stored and shared. To download the image to your laptop, make sure your Docker Engine is running, then execute the following command:

docker pull asancheg/cgub:latest


The image has been primarily tested on Ubuntu Linux as Host OS.

The download process may take some time, depending on your internet connection speed. After the image has been pulled, you can confirm its presence by executing the following command:

docker images

Running a container from the downloaded Image

To run a container from the course image, you will use the image you downloaded to create and start an isolated environment where the course software will run. In other words, running a container means launching a working instance of the image so you can use the tools and data it contains. To do this, open your terminal and run the following command:

docker run -it --name=<container_name> c851f55bb7f9 /bin/bash


The string c851f55bb7f9 is the image ID you obtained in step 1. This ID will be different on your computer, so make sure to check the correct one in the output of the docker images command. The text that appears after --name= specifies the name of the new container. You can replace it with any name you prefer, but remember it; you’ll need this name later if you want to start the same container again.

After running the previous command, you’ll see a new prompt in your terminal (starting with cguser@ followed by an arbitrary ID string).This means you are now inside a new Docker container (more precisely, in an interactive shell session within that container). You can think of a container as a running instance of a Docker image. Your container is based on Ubuntu, so you can now run any of the installed programs and explore or analyze the data included in the image.

Running an existing container

Running another container with a different name creates a new, separate instance of the image, like starting a fresh workspace. In contrast, using docker start on an existing container resumes the same environment you used before, with all your previous changes and files preserved.

docker start <container_name>
docker exec -it <container_name> /bin/bash


Remember to replace <container_name> with the actual name of your container.

Running your container with a shared Data directory

One of the most practical ways to access the data files generated inside your container is to set up a shared directory between the container and your host operating system. With this setup, any files you create or modify inside the linked directory of your running container will automatically appear in the corresponding directory on your host. In the same way, any data you place in that directory on your host will also be accessible from within the container.

If you want to use this configuration, replace the initial docker run... command from section 3 with this one:

docker run -it --name=<container_name> -v /home/<username>/shared:/home/cguser/shared <imageID> /bin/bash
docker run -it --name=<container_name> -v /Users/<username>/shared:/home/cguser/shared <imageID> /bin/bash
docker run -it --name=<container_name> -v /mnt/c/Users/<username>/shared:/home/cguser/shared <imageID> /bin/bash


…where /home/<username>/shared (on Linux), /Users/<username>/shared (on macOS) and /mnt/c/Users/<username>/shared (on Windows) are the directories on your host that you want to share with the container. Replace this path with the directory you wish to share in your system. REMEMBER to replace <container_name>, <username> (your username in the laptop) and <imageID> with the correct names.

TO AVOID PERMISSION ISSUES inside your container when accessing data in the shared directory, make sure that the directory on your host system has full read and write permissions for all users. On Linux and MacOS: chmod -R 777 /home/<username>/shared; On Windows: chmod -R 777 /mnt/c/Users/<username>/shared.

If you have already created another container with the same name (for example, from a previous docker run command), you will encounter an error. To fix this, either choose a different name for the new container, or remove the existing one with the conflicting name before creating the new container (see the “Other useful commands” section below).

Other useful commands


For any questions or technical difficulties related to the installation of Docker or the course image, feel free to contact Alejandro Sánchez at [].

You may also find the following free resources helpful for getting started with Docker:

Docker Official Getting Started Guide

Getting Started with Docker